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1.   INTRODUCTION 

1.1  What  is  ETS? 

Educational  Timesharing  System,  commonly  called  ETS,  is  a  multi-user, 
conversational  timesharing  system  designed  for  use  Toy  students  who  are  not 
acquainted  with  the  use  of  a  computer.   The  basic  system  consists  of  a 
monitor,  a  file  system,  an  input/output  system  and  a  command  string 
interpreter.   It  runs  on  the  PDP-11. 

1.2  What  is  timesharing? 

Timesharing  is  the  property  of  an  operating  system  that  enables  it 
to  give  multiple  users  the  illusion  of  being  exclusive  users.  Under  a 
timesharing  system  a  user  can  sit  down  at  a  console  and  in  one  or  more 
sessions  write,  debug,  assemble,  and  run  his  program,  all  in  an  interactive 
mode . 

1.3  What  facilities  does  ETS  provide? 

ETS  keeps  in  its  filing  system,  a  number  of  useful  systems  programs 
which  may  assist  you  in  your  programming.   These  include  an  editor  (EDETS), 
to  add,  delete,  or  alter  segments  of  your  source  program;  an  assembler 
(ASSETS),  to  assemble  your  source  program  written  in  PAL-11  into  a  machine 
language  module;  a  peripheral  device  handler  (PUPETS),  to  enable  you  to 
input  or  output  your  programs;  and  a  complete  debugging  package  (DEBETS) 
for  you  to  use  in  getting  those  nasty  little  bugs  out  of  your  code. 

l.h     How  do  you  talk  to  ETS? 
1A.1  Command  Mode 

Command  Mode  can  be  recognized  by  the  presence  of  a  period  at  the 
11  Lnnin  of  the  line  on  the  teletype.  This  is  the  signal  by  the  monitor 
that  he  is  ready  to  accept  a  command  from  you. 
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The  folio-wing  are  valid  commands: 

1.4.1.1  .HEnm  XXXXXX 

This  is  the  "hello"  or  login  command  which  tells  the  monitor  that 
you  want  to  be  a  user.   You  must  login  only  if  the  monitor  tells  you  to: 

LOGIN  PLEASE 
In  the  above  statement,  n  and  m  are  code  numbers  and  XXXXXX  is  a  code  word 
which  you  must  obtain  from  a  T.A.  or  staff  member. 

1.4.1.2  ^SI  n 

This  is  the  "size"  command  which  asks  the  monitor  to  reserve  for  you 
a  certain  amount  of  core.   If  you  do  not  give  the  monitor  this  command,  he 
will  automatically  reserve  IK  (1024  words).   In  the  above  statement  n  is  an 
integer  between  0  and  5  inclusive.   The  units  are  IX  words. 

1.4.1.3  iME  n 

This  is  the  "message"  command  which  asks  the  monitor  to  print  out 
for  you  the  error  message  designated  by  number  n.   It  is  not  necessary  for 
you  to  use  this  command  unless  you  receive  an  error  message. 

1.4.1.4  ^RU  XXXXXX 

This  is  the  "RUN"  command  which  requests  the  monitor  to  execute  a 
program  located  in  the  filing  system.  XXXXXX  is  the  name  of  requested 
program.   For  example, 

^RU  ASSETS 
vail  start  the  execution  of  the  assembler.   This  command,  if  successful,  will 
take  you  out  of  command  mode,  and  put  you  into  the  hands  of  the  executing 
program. 

1.4.1.5  j_BY 

This  is  the  "BYE"  command  which  requests  that  the  monitor  cancel 
your  login  command.  That  is,  after  this  command,  you  will  not  be  logged 
in  as  a  valid  user  of  the  system. 


ETS   Student's  Guide  -3-  July  1972 

1.4.2  Other  Modes 

When  not  in  command  mode,  you  will  probably  be  talking  basically  to 
an  individual  systems  program.  Each  of  these  has  its  own  special  character 
which  informs  you  of  who  you  are  talking  to  and  what  that  program  expects 
from  you.   See  the  following  sections  of  this  manual  for  details  of  these 
particular  programs. 

1.4.3  Special  Characters 

1.4.3.1  Carriage  return  [the  key  on  the  teletype  marked  "return"]  is  used 
as  a  terminator  or  "break"  character.   That  is,  it  is  used  at  the  end  of 
any  input  message  from  the  teletype.   For  example,  to  ask  the  system  to  give 
you  a  core  size  of  4K,  you  would  type  the  characters 

.81  4 
and  then  type  the  "return"  key  to  inform  the  system  that  you  have  completed 
the  message. 

1.4.3.2  Line  Feed  is  used  as  a  terminator  or  "break"  character  also  but 
should  only  be  used  within  certain  systems  programs  when  specifically 
requested  in  this  manual. 

1.4.3 -3  Control  B  [push  both  the  CNTL  key  and  the  B  key  simultaneously]  can 
be  used  to  inhibit  echo.   If  for  example  a  program  asks  you  for  a  code  word 
you  should  first  hit  Control  B,  then  the  code  word,  and  then  another  Control 
B  to  return  to  echo  mode.   This  will  simply  suppress  the  printing  of  the  code 
word  on  the  teletype  paper. 

1.4.3.4  Control  V  [push  both  the  CNTL  key  and  the  V  key  simultaneously] 
means  cancel  the  present  instruction.   The  particular  uses  of  this  will  be 
explained  later  within  each  systems  program  manual. 
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1.4.3.5  Control  Q  [push  both  the  CNTL  key  and  the  0,  key  simultaneously] 
means  "Quit  this  program."  When  Control  Q  is  typed,  the  character  string 
tQUIT  will  he  printed  on  the  teletype,  the  present  executing  program  will 

be  cancelled  and  you  will  be  returned  to  command  mode  with  the  monitor  again. 

1.4.3.6  Control  0  [push  both  the  CNTL  key  and  the  0  key  simultaneously] 
means  "Cancel  the  output."  That  is,  if  any  program  is  printing  a  message 
of  any  kind  to  you  and  you  don't  want  to  wait  for  it  to  complete,  just  type 
Control  0  and  the  printout  will  be  cancelled. 

1.4.3.7  Control  U  [push  both  the  CNTL  key  and  the  U  key  simultaneously] 
means  "Cancel  this  input  string."  This  should  be  used  to  cancel  anything 
you  type  on  the  teletype  since  your  last  carriage  return  or  line  feed.  Thus 
if  you  make  many  mistakes  in  typing  a  line,  don' t  type  return.  You  should 
type  Control  U  and  then  start  your  line  again. 

1.4.3«8  Rubout  on  the  teletype  is  equivalent  to  back  space  on  a  conventional 
typewriter.  To  backspace  n  characters  [i.e.,  cancel  last  n  characters] 
simply  type  rubout  n  times.   Typing  rubout  will  cause  the  teletype  to  retype 
the  characters  that  you  are  cancelling  delimited  by  slashes.   Thus  if  you 
spell  EDETS  wrong  by  typing  P  instead  of  T  and  immediately  rubout  and  then 
type  correctly,  your  teletype  paper  would  look  like: 

^RU  EDEP\P\TS 
The  \P\  indicates  that  the  P  has  been  cancelled. 
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2.   Peripheral  Utility  Package  for  ETS 

2.1  PUPETS  is  a  generalized  file  utility  package  "with  which  you  can 
manage  your  files.   It  is  invoked  by  typing 

RUN  PUPETS 
PUPETS  will  then  identify  itself  and  type  a  hash  mark  (#)  to  indicate 
that  it  is  ready  to  accept  a  command  string. 

2.2  A  command  string  consists  of  up  to  six  file  strings.   Separated  by 
commas.  A  file  string  consists  of  a  file  name  and  a  switch  list 
separated  by  a  slash. 

2.2.1  A  file  name  consists  of  three  fields: 

1.  A  device  name 

2.  A  file  label 

3.  A  project  programmer  number 

2.2.1.1  The  names  of  the  devices  are: 

CDR  Card  Reader 

LPT  Line  Printer 

I'l'i;  Paper  Tape  Reader 

PTP  Paper  Tape  Punch 

DSK  Disk 

KBD  User's  Teletype 

TTY  Any  Teletype 

DTA  DEC  Tape 

TTY  and  DTA  require  a  device  number  after  the  name.   TTYO  is  the  same 

as  KBD.   The  device  name  is  not  necessary  for  disk  files  since  disk 

will  be  assumed  if  no  device  name  appears.   Device  names  are 

terminated  by  a  colon  ( : ) . 

2.2.1.2  The  file  label  consists  of  up  to  six  characters  plus  an 

extension  of  up  to  three  characters  set  off  by  a  period.   Characters 

may  be  alphabetic,  numeric,  or  the  dollar  sign.   The  file  label  is 

optional  for  devices  other  than  disk  and  DECtape. 
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2.2.1.3  The  project  programmer  number  is  enclosed  in  square  brackets 
and  consists  of  two  numbers  separated  by  a  comma.   If  no  project 
programmer  number  appears,  yours  will  be  assumed. 
2.2.1.4-  The  following  are  valid  file  names: 

1.  CDR: 

2.  TTY3: 

3.  PROGRM.BIN[15,3] 

4.  FILEA 

2.2.2  A  switch  list  consists  of  an  arbitrary  number  of  switch  strings 

separated  by  semi-colons  (;).   Switch  strings  consist  of  one  switch  followed 

by  parameters  separated  from  each  other  and  from  the  switch  by  colons  (:). 

2.2.2.1  The  following  are  the  switches  presently  defined: 

OP  Open  the  file. 

CL  Close  the  file. 

RE  Rename  the  file . 

PR  Change  the  protection  on  the  file. 

DE  Delete  the  file  from  the  UFD. 

2.2.2.1.1  Open:   If  no  parameters  are  present,  it  will  give  an  error  if  the 
file  does  not  exist.   The  following  parameters  will  cause  the  file  to  be 
created: 

CN      Create  if  file  does  not  exist.   Otherwise,  just  open  it. 

EE      Create  if  file  does  not  exist.   If  file  already  exists,  flag 
an  error. 

2.2.2.1.2  Close:   Close  the  file. 

2.2.2.1.3  Rename:   Parameter  is  the  new  name  for  the  file  and  must  be  last 
in  the  switch  string.   You  must  be  the  owner  of  the  file  to  rename  it. 

2.2.2.1.4  Protect:   Parameter  is  new  protection  code  for  the  file.   You 
must  be  the  owner  of  the  file  to  change  protection. 
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2.2.2.1.5  Delete:   Remove  the  file  from  the  UFD.   You  must  be  the  owner 

of  the  file  to  delete  it. 

2.2.2.2  If  no  switches  are  found,  OP  and  CL  will  be  assumed  with  no 

parameters. 

2.2.3  The  following  are  examples  of  valid  command  strings: 

1.  FILEA/OP:   CN;  PR:  6;  CL,  CDR: 

2.  FILEB/RE:      FILEC.EXT,    FILED/DE 

2.3  PUPETS  may  also  be  used  to  transfer  data  between  files  by  typing  a 
transfer  string  between  the  object  files  (files  into  which  data  will  be 
transferred)  and  the  source  files  (files  from  which  data  will  be  taken). 
The  transfer  string  is  of  the  form 

<mode  :  parameter  < 
"parameter"  is  an  unsigned  octal  number  less  than  200000. 

2.3.1  The  mode  indicates  the  nature  of  the  data  and  how  the  parameter  is 
to  be  interpreted. 

2.3.1.1  BI  indicates  that  the  data  is  binary,  e.g.,  an  assembled  program. 
Any  parameter  will  be  ignored. 

2.3.1.2  LI  indicates  that  the  data  is  ASCII.   The  parameter  indicates 
the  number  of  lines  to  be  placed  in  each  object  file. 

2.3.1.3  CH  indicates  that  the  data  is  ASCII.   The  parameter  indicates 
the  number  of  characters  to  be  placed  in  each  object  file. 

2.3.2  Data  is  taken  from  the  source  files  in  order  from  left  to  right  and 
concatenated  to  form  one  data  stream.   Object  files  are  filled  in  order 
from  left  to  right  as  indicated  by  the  transfer  string. 

2.3.2.1  If  no  parameter  is  present  or  the  parameter  is  zero,  all  of  the 
data  will  be  transferred  to  the  first  object  file. 
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2.3*2.2     If  data  remains   to  "be  transferred  after  all  object  files  have  been 
filled,    the  remainder  is  added  to  the  last  object  file. 

2.3 . 3     The  following  are  examples  of  command  strings: 

a.  FILEA,    FILEB  <LI:500<CDR: 

This  will  place  the  first  500  lines  in  FILEA,  and  any  remaining 
lines  in  FILEB.   If  fewer  than  500  cards  are  read,  FILEB  will  not 
be  affected. 

b.  FILEC<CH:<PTR: 

This  will  place  all  of  the  data  on  a  paper  tape,  followed  by  the 
data  filed  in  FILEC. 

c.  FILEF,    FILEG<BI:<PTR: 

This  will  place  all  of  the  data  on  a  paper  tape  in  FILEF.   FILEG 
will  not  be  affected. 

2  A  You  may  obtain  information  from  your  file  directory  by  typing  /DI  any 
place  in  the  command  string  not  within  a  file  string.  After  executing  all 
switches  in  the  command  string,  PUPETS  will  type  the  names  of  the  files  in 
your  file  directory  and  their  size  in  disk  blocks  in  the  order  that  they 
were  created. 

2*5  It  is  necessary  to  be  partially  aware  of  what  PUPETS  will  be  doing 
when  you  type  a  command  string. 

2.5.1.1  All  files  in  the  string  will  first  be  opened  (whether  or  not  the 
open  switch  is  present).  Since  no  more  than  six  files  may  be  open  at  a 
time,  you  should  not  leave  too  many  files  open  from  previous  command 
strings. 

2.5.1.2  Files  you  asked  to  be  renamed  will  then  be  renamed. 

2.5.1.3  Any  transfer  specified  will  be  performed. 
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2,5.lA  Protection  codes  will  be  changed. 

2.5.1.5  Files  marked  to  be  deleted  will  be  removed. 

2.5.1.6  Finally  files  with  which  the  open  switch  was  not  present  and/or 
the  close  switch  was  present  will  be  closed. 

2.5.2  If  at  anypoint  an  error  in  protection,  syntax,  etc.  is  found,  a  message 
will  be  typed  and  files  will  be  returned  to  their  state  before  the  command 
string  was  typed. 

2.6  To  exit  from  PUPETS  type  control  Q,  in  response  to  a  hash  mark. 

2.7  The  current  version  of  PUPETS  has  the  following  problems: 

1.  When  transferring  from  one  disk  file  to  another  in  binary  mode, 
the  object  file  will  be  one  block  longer  than  the  source  file. 
Solution:  None  known  at  present. 

2.  If  the  protection  code  on  a  file  is  changed  and  then  the  user 
tries  to  delete,  rename,  or  write  on  the  file,  he  may  get  a 
protection  violation  message,  particularly  if  the  change  in 
protection  was  to  remove  some  write  protection. 

Solution:  After  changing  the  protection  code,  log  out  then  log  back 

in. 

').   If  the  card  reader  runs  out  of  cards  before  finding  an  end  of 

file  card  in  LI  or  CH  mode,  the  CR-LF  on  the  last  card  is  lost. 

Solution:   Be  sure  there  is  an  end  of  file  card  at  the  end  of  your 

deck,  and  keep  cards  in  the  hopper  until  the  end  if  reached. 

k.      If  an  error  occurs  on  the  card  reader  (feed  check,  stacker  fail, 

timing,  etc.)  part  or  all  of  the  card  on  which  the  error  occurred 

may  be  lost. 
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Solution:   In  BI  mode,  reread  the  deck.   In  LI  or  CH  mode,  keep 
track  of  where  the  error  occurred  and  correct  it  with  EDETS. 
5.   DECtapes  are  not  supported  by  PUPETS. 
Solution:  Use  MAGETS. 
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3*   Text  Editor  for  the  Edcuational 
Timesharing  System  (EDETS) 


EDETS  is  a  text  editor  for  use  with  the  Educational  Timesharing 
System  (ETS).   It  allows  the  user  to  display  any  text  on  the  teletype,  and 
make  corrections  and  improvements  to  it  using  simple  one  character  commands. 

3.1  Command  Mode  and  Text  Mode 

There  are  two  different  modes  of  operation  for  EDETS:   Command 
Mode  and  Text  Mode.   In  Command  Mode  the  user  is  allowed  to  type  in  one  of 
22  possible  commands  for  the  editor  to  perform.   While  in  Text  Mode  the 
user  may  type  in  any  text  he  wishes.  He  may  not  type  in  a  command  without 
first  entering  Command  Mode  because  EDETS  will  not  recognize  the  command, 
and  instead  it  will  treat  it  as  text.   To  enter  Command  Mode  from  Text  Mode 
a  line  feed  (LF)  must  be. typed.  EDETS  will  respond  by  typing  a  #  to  signify 
that  it  is  in  Command  Mode. 

Caution:  The  line  feed  will  not  be  stored  as  part  of  the 
text.   However,  a  carriage  return  (CR)  will  cause  EDETS 
to  include  in  the  text  a  CR-LF  sequence  which  designates  the 
end  of  line  of  text.   Therefore  it  is  important  to  type  a 
CR  before  entering  Command  Mode,  or  EDETS  will  append  the 
next  line  to  the  line  just  typed  because  there  is  no  CR-LF 
to  designate  the  end  of  the  line.   Entering  Text  Mode  is  done 
through  various  commands  of  EDETS.   These  commands  require 
text  input  and  thus  cause  EDETS  to  go  into  Text  Mode. 
Example:   #  INSERT 
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This  command  tells  EDETS  to  insert  text.  Thus  EDETS  goes  into 
Text  Mode  so  that  the  text  may  be  typed  in.  Note:  The  #  was  printed  by 
EDETS  to  signify  it  is  in  Command  Mode. 

3.2  Command  Structure 

3.2.1  The  Character  Location  Counter  (DOT) 

Most  EDETS  commands  are  performed  with  respect  to  the  movable 
reference  point,  DOT.   This  pointer  should  be  thought  of  as  lying  between 
two  successive  characters.  EDETS  provides  commands  to  move  DOT  so  that 
any  character  in  text  may  be  referenced. 

3.2.2  Command  Format 

There  are  basically  two  different  command  formats.   The  first 
type  has  no  arguments  and  consists  of  just  the  command  word. 

Example:  #  BEGINNING 
This  will  move  DOT  to  the  beginning  of  text.  EDETS  uses  only  the  first 
letter  of  command  word  to  designate  the  command.   Thus  #B  will  result  in 
DOT  being  moved  to  the  beginning  of  text  too. 

The  second  type  requires  some  argument  n.  n  may  be  any  positive 

15 
or  negative  number  from  1  to  327^7  (2  -l).   If  no  sign  precedes  n  it  is 

assumed  positive.   The  command  is  of  the  form  +n  Command  or  Command  +n. 

Since  EDETS  uses  only  the  first  letter  of  the  command  the  entire  command 

word  need  not  be  used. 

Example:  #  ADVANCE  10 
#A  10 

#  10  ADVANCE 

#  10  A 

All  four  commands  will  move  DOT  to  the  beginning  of  the  10th  line  after  the 
current  line  that  DOT  is  pointing  to. 
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3.3     Commands 

There  are  four  basic  groups  of  commands  for  EDETS: 

(1)  Commands  for  positioning  DOT. 

(2)  Commands  for  inserting,  deleting,  and  exchanging  text 
portions. 

(3)  Commands  for  searching  for  and  manipulating  strings  of 
characters. 

(k)      Commands  for  listing. 

3.3*1  Commands  for  Positioning  DOT 

Advance   -  Advance  DOT  to  the  beginning  of  the  nth  line  from 
DOT.   If  n=0  DOT  will  he  moved  to  the  beginning  of 
the  current  line. 

Beginning  -  Move  DOT  to  the  beginning  of  text.   No  argument 
is  used. 

End       -  Move  DOT  to  the  end  of  text.  No  argument  is  used. 

Go       -  Go  to  the  previously  marked  location  in  text.  No 
argument  is  needed.   This  command  is  used  in 
conjunction  with  MARK. 

Jump      -  Jump  forward  +n  or  backward  -n  characters.   If 

n=0  no  action  is  needed.  Caution:   If  jumping  into 
the  next  line  remember  that  there  is  a  CR-LF  in 
the  text  which  must  be  jumped  over. 

Mark      -  Mark  the  current  location  of  DOT  in  the  text. 

This  command  is  used  in  conjunction  with  the  GO 
command. 

3.3.2  Commands  for  Inserting,  Deleting,  and  Exchanging  Text  Portions 

Change    -  Delete  +n  characters  starting  at  DOT  and  insert 
in  their  place,  text  of  arbitrary  length. 

Delete    -  Delete  +n  characters  starting  at  DOT.   If  n=0  no 
action  is  taken. 

Insert  -  Insert  text  of  an  arbitrary  length  starting  at  DOT 
until  a  line  feed  is  typed  to  terminate  text  mode. 
The  line  feed  is  not  included  as  part  of  the  text. 
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Kill 


-  Kill  +n  lines  starting  with  the  current  line.  If 
n=0  no  action  is  taken. 


Replace    -  Replace  +  lines  starting  with  the  current  line 

and  insert  in  its  place,  text  of  arbitrary  length. 

3.5.3  Commands  for  Seeking  and  Manipulating  Character  Strings 

Find       -  Find  the  +nth  occurrence  of  a  character  string  of 
up  to  72  characters  starting  at  DOT.  When  typing 
in  the  string  to  be  searched  for  terminate  it  with 
a  LF.   The  LF  is  not  included  in  the  search 
unless  it  was  the  only  character  typed.   If  the 
LF  is  preceded  by  a  CR  the  CR-LF  sequence  is 
included  in  the  search.   If  n=0,  n=l  is  assumed. 

Prefix     -  Prefix  +n  occurrences,  starting  at  DOT,  of  Text  1 
with  Text  2*.   The  same  rules  apply  for  CR's  and 
LF's  as  are  defined  for  FIND. 

Suffix     -  Suffix  +n  occurrences,  starting  at  DOT,  of  Text  1 
with  Text  2*.   The  same  rules  apply  for  CR's  and 
LF's  as  are  defined  for  FIND. 

Wipeout    -  Wipeout  +n  occurrences,  starting  at  DOT.   The 

same  rules  apply  for  CR's  and  LF's  as  are  defined 
for  FIND. 

Xchange    -  Exchange  +n  occurrences,  starting  at  DOT,  of  Text  1 
with  Text  2*.      The  same  rules  apply  for  CR's  and 
LF's  as  are  defined  for  FIND. 

^Prefix,  Suffix,  and  Xchange  require  two  text  strings.  Neither  can  be  more 
than  kO   characters  in  length,  but  they  need  not  be  of  equal  length.   Text  1 
is  typed  first  then  Text  2.   If  either  is  longer  than  ^0  characters  or  a 
control  V  is  typed  before  the  end  of  Text  2,  no  action  will  be  taken. 

3.3*^  Commands  for  Listing 


Hole 
List 


-  List  the  entire  text.   No  argument  is  needed. 

-  List  +n   lines  starting  with  the  current  line.   If 
n=0  no  action  is  taken. 


Number     -  List  the  current  character  position  of  DOT  in 
octal.  No  argument  is  necessary. 

Type       -  Type  +n  characters  beginning  at  DOT.   If  n=0  no 
action  is  taken. 

Verify     -  Verify  the  current  line  with  an  upward  arrow  showing 
where  DOT  is . 
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3.3-5  Miscellaneous  Commands 

Control  Q,  -  Quit  editing.   Puts  the  text  in  the  disk  file  and 
returns  to  monitor. 


3.^-  Operating  Procedure 
3-^.1  Invoking  EDETS 

To  invoke  EDETS  simply  type  on  the  teletype  RUN  EDETS. 
3 A. 2  Initial  Dialogue 

EDETS  will  identify  itself  and  ask  for  the  name  of  the  file  to 
be  edited.  Your  response  should  be: 

(1)  The  name  of  a  disc  file  of  which  you  are  the  owner  or  a 
file  which  has  not  been  created.   If  the  file  already  exists  it 
need  not  be  open.   If  you  do  not  wish  to  copy  anything  into  the 
file  type  a  carriage  return  (CR)  and  EDETS  will  enter  Command 
Mode. 

(2)  If  you  wish  to  copy  text  into  the  file  type  a  transfer  mark 
(<)  following  the  file  name  and  then  type  the  name  of  either 
another  file  or  an  input  device.  Example:   To  copy  source  from 
the  paper  tape  reader  into  a  file  name  FILE  type  FILE<PTR: 
After  the  copy  is  finished  EDETS  enters  Command  Mode. 

3.^.3  Cautions  when  Copying 

EDETS  uses  two  successive  form  feeds  to  signify  the  end  of  the 
file.   Because  of  this  caution  must  be  taken  when  copying  text  into  files. 
3.^.3.1  Copying  from  Teletype 

If  there  is  a  transfer  mark  and  a  teletype  was  specified  as  the 
input  device  EDETS  will  assume  that  there  is  nothing  in  the  disc  file  and 
will  enter  Command  Mode. 
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3,1]-. 3. 2  Copying  from  the  Card  Reader 

When  copying  from  cards  two  form  feeds  will  "be  inserted  after 
the  last  card  is  read. 
3.^.3 .3  Copying  from  the  Paper  Tape  Reader 

When  copying  paper  tape  two  form  feeds  will  he  inserted  if  the 
end  of  the  tape  is  reached  before  two  form  feeds  are  found.   Thus  if  no 
form  feeds  exist  on  the  tape  the  trailer  tape  will  be  inserted  as  part  of 
the  text.   These  trailing  characters  should  be  deleted  by  you  before  doing 
any  editing. 
J.k^J.k     Copying  from  Another  File 

If  a  disk  file  is  being  copied  and  no  form  feeds  are  found  before 
the  end  of  the  file  is  reached  EDETS  will  insert  two  form  feeds  and  type 
a  warning  message.   This  will  probably  mean  there  is  some  garbage  at  the 
end  of  your  file.   This  garbage  should  be  deleted  before  continuing  to  edit, 

3-5  Re  s  tr i  ct i  ons 
3.5.1  File  Size 

EDETS  cannot  accept  a  file  containing  more  than  32767  (2  -l) 
characters.   If  the  file  is  initially  found  to  be  larger  than  this,  EDETS 
will  type  a  message  and  return  to  monitor  mode.   If  during  editing,  an 
insertion  would  cause  the  limit  to  be  exceeded,  a  message  is  typed  and  the 
insertion  is  not  performed. 
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k.     ASSETS  User's  Guide 

h.      Description 

ASSETS  is  a  modified  version  of  the  PAL-11A  assembler.   Its  input 
is  a  disk  file  containing  source  statements  and  its  output  is  an  absolute 
binary  file.   It  presently  has  no  provision  for  performing  linkage  editing. 

^-.1  Using  Assets 

ASSETS  requires  5K  of  core  in  order  to  execute.   It  is  initiated 
by  using  the  following  command  string  when  the  system  is  in  command  mode. 

.Size  5 

.RUn  ASSETS 

(The  lower  case  letters  are  optional,  the  periods  are  typed  by 

the  system. ) 

ASSETS  will  respond  with: 

SOURCE^ 
In  response,  the  user  types  from  one  to  four  file  names  separated  by  commas. 
The  files  are  assembled  as  if  they  were  a  single  large  file  consisting  of 
the  concatenation  of  the  input  files.  ASSETS  will  check  the  validity  of 
the  source  files  and  if  it  is  satisfied  with  them,  it  will  respond 

BINARY= 
The  user  responds  by  typing  a  file  name  which  may  or  may  not  exist.  ASSETS 
automatically  adds  an  extension  of  the  form  BIN  to  the  file  name  (e.g.,  FILEX 
becomes  FILEX.BIN).   If  this  file  exists,  ASSETS  will  open  it  for  output. 
If  it  does  not  exist,  it  will  create  a  file  with  that  name  and  open  it. 
(Note  that  for  files  which  do  exist,  ASSETS  actually  deletes  and  re-creates 
them  in  case  the  new  object  listing  is  shorter  than  the  old).  ASSETS  will 
then  type  out 
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LISTING= 

to  which  the  user  responds  with  a  single  character  as  follows: 

N  -  produce  no  listing 

E  -  list  only  statements  containing  errors  and  undefined 
symbols  on  the  teletype 

T  -  produce  a  complete  listing  on  the  teletype 

L  -  produce  a  complete  listing  on  the  line  printer. 

(if  the  line  printer  is  currently  being  used,  a  message 

will  be  printed  saying  that  the  line  printer  is  unavailable 

after  which  it  will  request  another  choice.) 

If  at  any  time  during  the  assembly  it  is  desired  to  terminate 

the  assembly,  the  user  may  type  tQ,  (CNTL  key  and  Q)  and  ASSETS  will  terminate 

as  soon  as  it  closes  all  files  and  releases  the  line  printer  if  it  is 

being  used. 

k.2.     Non-Standard  Features 

1.  All  registers  (RO,  Rl,  ...  SP,  PC),  carriage  return  (CR),  and 
line  feed  (LF)  are  already  defined. 

2.  The  assembly  directive  .NLIST  may  be  used  anywhere  in  the 
source  program  to  stop  the  generation  of  a  listing  at  that  point. 
.LIST  may  be  used  to  resume  the  listing  if  it  is  specified  in 
the  LISTING  command  to  ASSETS. 

3.  The  directives  .EJECT  and  .PAGE  will  cause  the  source  listing 
to  continue  on  a  new  page. 

k.      If  a  .END  statement  is  inadvertently  left  out,  ASSETS  will 
supply  one  at  the  end  of  the  last  file. 
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5.   DEBETS  Command  Manual 

DEBETS  is  an  interactive  debugging  package  for  student  use  with 
ETS.   Users  can  enter  commands  to  load  programs,  execute  them,  and  to 
manipulate  and  examine  their  allotted  core  space  at  will.   Like  other  ETS 
programs  (EDETS,  PUPETS),  DEBETS  has  a  'command  mode'  which  is  announced 
by  the  typing  of  a  special  character  (for  DEBETS,  a  colon)  and  in  which  a 
line  of  input  containing  commands  is  read,  examined  and  executed.  With  a 
few  exceptions,  DEBETS  commands  consist  of  a  single  character  accompanied 
by  some  numerical  parameters,  usually  addresses.   These  parameters  must 
invariably  be  octal  numbers,  or  an  error  is  flagged  and  DEBETS  returns  to 
command  mode.  Any  addresses  must  be  within  the  bounds  allotted  to  the 
user.   (See  section  V.)  As  a  rule,  if  a  syntax  error  is  made,  DEBETS 
types  '?'  and  returns  to  command  mode.   (This  is  something  of  a  hardship 
on  beginners,  and  will  be  changed.   Space  limitations  at  present  make  it 
inadvisable  to  put  in  the  extra  code  and  message  strings.) 

The  remainder  of  this  manual  describes  the  various  commands. 
Following  is  a  short  table  of  contents: 

5.1  Opening,  Examining  and  Changing  Individual  Locations 

5-2  ASCII  Insertion 

5. 3  Dumping  Core 

5.k     Disassemblies 

5.5  Loading  a  Program  -  Changing  Size 

5.6  Setting  Breakpoints,  Executing  a  Program,  Error  Messages,  I/O 
Conventions 


ETS   Student's  Guide  -20-  July  1972 

5.7  Special  Routines: 

Examining  registers 

Examining  the  breakpoint  table 

Dumping  the  instruction  count 

Dumping  all  registers 

Opening  the  print  register 

Dumping  the  PC  stack 

Dumping  the  condition  code,  opening  the  status  register 

5.8  Dynamic  Symbol  Table 

5.9  Storing  and  later  Retrieveal  of  DEBETS  Command  Strings 
5.10  Symbolic  Program  Patching — the  Mini -Assembler 

5.1  Opening,  Examining  and  Changing  Individual  Locations 

To  examine  a  core  location,  type  the  address  followed  by  a  slash 
('/')  to  examine  the  word  at  that  location,  or  a  backslash  (f\f)  to  examine 
the  byte  at  that  location.   DEBETS  prints  the  contents  in  the  format 
'=<value>',  then  returns  to  command  mode  without  typing  the  standard  colon. 
The  location  is  now  'open'  and  may  be  modified.   The  following  inputs  in 
particular  are  of  use  while  it  is  open: 

5.1.1  Typing  a  line  feed  causes  DEBETS  to  open  and  dump  the  next  sequential 
location.   If  an  octal  number  was  typed  before  the  <LF>,  this  is  inserted 
into  the  word  or  byte  presently  open  before  the  next  is  opened. 

5.1.2  Typing  <CR>  causes  DEBETS  to  insert  any  number  typed  into  the 
presently  open  location,  'close*  it,  and  return  to  normal  command  mode  with 
a  colon. 

5.1.3  Typing  't  '  (shift-N)  causes  DEBETS  to  insert  any  number  typed  into 
the  presently  open  location,  and  open  the  immediately  preceding  location. 
(DEBETS  decrements  or  adds  1  or  2  depending  on  whether  the  first  location 
opened  is  a  byte  or  a  word. ) 
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5.1.4  If  a  word  is  open,  typing  '©'  causes  DEBETS  to  take  the  ASCII 
character  following  the  quote  mark  and  insert  it  into  the  presently  open 
location.   If  a  word  is  open,  the  high  byte  becomes  zero.   This  can  be 
used  for  changing  individual  bytes  of  a  character  string. 

5.2  ASCII  Insertion 

DEBETS  allows  the  user  to  change  an  entire  character  string  at 
will.   Typing  '<address>;A'  causes  DEBETS  to  input  a  new  line  from  the 
user  to  be  placed  in  core  starting  at  <address>.  Every  byte  of  the  line 
is  placed  in  core  except  the  terminal  character  of  the  line  (CR,  LF,  or 
ALTMODE).   DEBETS  then  opens  the  byte  immediately  following  the  st  ing  in 
core  and  awaits  new  commands.   In  this  way  the  user  can  add,  if  he  wishes, 
some  special  terminal  to  the  end  of  the  string. 

5.3  Dumping  Core 

Core  may  be  dumped  in  three  modes — word,  byte,  or  ASCII.   In 
word  mode,  k   words  are  dumped  per  line,  in  k   6-character  strings  followed 
by  the  ASCII  representation  of  those  8  bytes.   In  byte  mode,  8  bytes  are 
dumped  per  line,  in  8  3 -character  strings,  followed  by  the  ASCII 
representation  (which  is  delimited  by  asterisks).   In  ASCII  mode,  l6 
bytes  are  dumped  in  ASCII  per  line,  with  non-printing  characters  printed 
as  '.'. 

A  dump  may  be  specified  in  one  of  two  ways: 

(1)  By  typing  '<low  address>;  <high  address>D'  followed  by 
'W,  'B',  or  'A'  to  indicate  the  mode,  or 

(2)  By  typing  '  ;<low  address>D'  followed  by  'W,  'B',  or  'A' 
followed  by  N  dots  ('.'),  to  produce  N+l  lines  of  output. 
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When  the  dump  is  complete,  DEBETS  returns  to  scanning  the 
original  input  string,  so  that  multiple  dump  commands  may  be  given  in  the 
same  line  of  input. 
Examples : 

'100;200DW  *)'  to  dump  words  from  100  to  200. 
'20;30DA^  '  to  dump  ASCII  from  20  to  30. 
';1006DB. ..  f)  '  to  dump  bytes  in  k-   lines  starting  at  1006. 
or  several  at  once: 

' 100 ; 200DW  20 ; 30DA  ; 1006DB . . . ^  * 

5»b-     Disassemblies 

If  the  user  wishes  to  check  some  instruction  patches  he  has  made, 
he  can  do  so  by  typing  t<address>;D' .  DEBETS  then  takes  the  word  at 
<address>  (provided  <address>  is  even),  parses  it,  and  prints  a  mnemonic 
if  it  is  a  valid  opcode,  or  else  prints  the  message  'JIMK'.   It  then  waits 
for  the  user  to  type  a  line  feed  to  disassemble  the  next  instruction.   If 
line  feed  is  not  typed,  DEBETS  returns  to  command  mode. 

5.5  Loading  a  Program  -  Changing  Size 

5« 5*1     To  load  a  program  the  user  types  'KCK>',  DEBETS  responds  by 
first  typing  the  size  at  which  it  is  running  (this  is  forced  to  3  when  DEBETS 
starts  executing).   The  user  may  alter  the  size  by  typing  3,  k,    or  5,  or 
type  a  terminal  to  bypass  this  and  keep  the  same  size.   The  size  at  which 
DEBETS  is  running  controls  the  amount  of  storage  the  user  may  access.  At 
size  3,  the  highest  address  he  can  reference  is  about  2000  (octal);  at 
size  k,    about  6000;  at  size  5>  about  12000.   (The  user  may  quickly 
ascertain  his  highest  referenceable  address  by  typing  '.H<CB>'  when  in 
normal  command  mode.) 
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5.5.2  Next  DEBETS  requests  the  name  of  a  load  file.   If  a  terminal  is 
typed  in  response,  DEBETS  returns  to  command  mode.   Otherwise,  DEBETS 
inputs  the  name  (which  must  be  terminated  by  a  <CB>,  <LF>,  or  <ALTMODE>, 
not  a  hundred  blanks! ),  and  attempts  to  open  the  file.   If  it  fails,  a 
message  is  typed  and  DEBETS  again  requests  the  file  name.  When  it  finally 
gets  a  valid  file  open,  it  requests  a  load  offset.   Normally  this  will  be 
zero,  but  a  nonzero  offset  causes  the  program  to  be  loaded  starting  at 
address  <offset>.   Thus,  location  1000  in  the  assembler  listing  corresponds 
to  location  1000+<offset>  of  the  user's  area.   This  facility  is  useful 

for  testing  relocatability  of  a  program. 

5.5.3  Finally,  when  the  load  file  is  open  and  the  offset  is  determined  or 
it  defaults  to  0,  DEBETS  attempts  to  load  the  program.   If  an  error  occurs, 

a  message  is  typed,  and  DEBETS  requests  a  load-file  name  again;  otherwise, 

DEBETS  types  'LOADED  O.K.',  then  requests  a  file  name. 

<N0TE:   If  the  load  file  name  has  a  .BIN  extension,  this  must  be  included. > 

5.6  Setting  Breakpoints,  Executing  a  Program,  Error  Messages, 
I/O  Conventions 

5.6.1  Breakpoints 

A  'breakpoint'  is  any  (word)  location  specified  as  such  by  the 
user.   When  the  user's  program  is  executing  and  it  arrives  at  a  breakpoint 
location,  a  message  of  the  form  !Bnnn:<address>'is  typed  and  DEBETS  returns 
to  command  mode.   The  'nnn'  in  the  message  is  the  number  of  the  breakpoint, 
of  which  there  may  be  a  maximum  of  30fi,  numbered  0  to  27q.   The  user  may 
create  or  delete  breakpoints  as  follows: 

Create:   '<address>;B'  to  make  <address>  the  first  available 
breakpoint  in  the  breakpoint  table. 

Delete:  ';B'  to  delete  all  breakpoints. 

' ;nB'  to  delete  breakpoint  number  n. 
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<NOTE:  Multiple  creates  and  deletes  may  be  done  in  the  same  line  of  input. > 

To  be  more  specific:  when  the  user  starts  his  program  executing, 
all  the  locations  he  has  specified  as  breakpoints  are  saved  and  replaced 
by  HALT  instructions.   Before  DEBETS  executes  any  instruction,  it  checks 
to  see  if  it  is  HALT.   If  it  is,  DEBETS  checks  to  see  if  the  HALT  is  at 
the  address  of  a  breakpoint.   If  it  is,  DEBETS  decrements  a  repeat  count 
for  that  breakpoint.   If  the  count  becomes  zero,  DEBETS  types  the  message 
'Bnnn:<address>',  restores  the  original  contents  of  all  breakpoint  locations, 
and  returns  to  command  mode.   (The  repeat  count  is  normally  1 — see  section 
VII  on  how  to  change  it,  under  '.B'.)   If  the  HALT  is  not  at  a  breakpoint 
address,  DEBETS  types  'BE :<address>',  restores  breakpoint  locations,  and 
returns  to  command  mode.   (The  'BE'  is  for  'Bad  Entry'  or  maybe  'Breakpoint 
Error' . ) 

5.6.2  Program  Execution  Commands 

Program  execution  may  be  started  in  two  possible  ways.   In 
brief,  the  calling  sequences  are: 
'P<print  mode>' 

or   '<address>;<instruction  limit>G<print  mode>'  . 
5.6.2.1  The  first  is  a  'Proceed'  and  is  to  be  used  mainly  in  conjunction  with 
breakpoints.   DEBETS  takes  whatever  address  is  in  the  user's  program 
counter,  and  attempts  to  start  execution  at  that  address.   If  it  is  the 
address  of  a  breakpoint,  the  breakpoint  is  ignored  and  the  normal 
instruction  there  is  executed.  After  execution  leaves  this  point,  the 
breakpoint  is  activated.   THIS  IS  PECULIAR  TO  PROCEED,  and  is  designed 
for  situations  when  execution  has  been  stopped  at  a  breakpoint,  so  that 
it  can  PROCEED  normally  when  a  P-command  is  typed.   The  meaning  of 
<print  mode>  is  explained  below. 
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5.6.2.2    The  G-command  is  used  to  start  execution  at  the  address 
<address>  typed  by  the  user.   Provided  <address>  is  even  and  within  bounds, 
it  is  loaded  into  the  user's  program  counter  and  execution  begins.   In 
this  case,  if  <address>  is  a  breakpoint,  there  will  be  an  immediate 
breakpoint  interruption  and  no  instructions  will  have  been  executed.  As 
for  the  other  parameters : 

5.6.2.2.1  -^instruction  limit>  is  the  maximum  number  of  instructions 
DEBETS  will  execute  before  typing  a  message  of  some  kind.   If  this  number 
is  N,  then,  after  executing  N  instructions,  and  assuming  no  breakpoints  or 
fatal  errors  occurred  along  the  way,  DEBETS  types  the  address  of  the  last 
instruction  executed,  followed  by  a  '?'  to  inquire  if  the  user  wants  to 

go  on.  At  this  point  the  user  can  type  in  an  optional  new  <print  mode>. 
DEBETS  then  executes  N  more  instructions.  If  instruction  limit>  is  not 
typed,  it  defaults  to  100  (decimal). 

5.6.2.2.2  <print  mode>  is  any  octal  number.   If  it  is  present  at  all, 
<instruction  limit>  is  ignored  (except  in  the  special  case  when  <print  mode> 
is  a  negative  number — then  DEBETS  acts  as  if  it  weren't  present,  i.e.,  no 
<print  mode>  and  negative  <print  mode>  are  treated  alike).   The  print  mode 
is  used  to  control  diagnostic  output  for  each  instruction  executed.   In 

the  present  release  of  DEBETS,  this  is  anything  but  fancy:   If  the  print 
mode  is  even,  DEBETS  prints  the  PC,  opcode,  and  mnemonic  for  each 
instruction.   In  either  case,  when  the  print  is  performed,  DEBETS  then 
waits  for  a  user  response.   The  following  alternative  exist: 

(a)  If  the  first  character  typed  is  '/',  DEBETS 
continues  executing  the  program  in  the  same 
manner. 
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(b)  If  a  number  is  typed,  DEBETS  takes  it  for  a  new 
print  mode  and  continues  executing  the  program. 

(c)  If  <CR>,  <LF>  or  <ALTM0DE>  is  typed,  DEBETS 
continues  executing  the  program  with  no  print  for 
each  instruction,  using  whatever  instruction 
limit  was  last  specified  in  a  G~command,  or  the 
default  of  1001Q. 

(d)  If  control-V  or  control-Q,  is  typed,  DEBETS  returns 
to  command  mode. 

<NOTE:  These  rules  apply  also  to  typing  a  reply  to  the 
instruction — limit  interruption^ 

5.6.2.3   Examples: 

(1)  ' 1000;G'      start  execution  at  1000,  with  no  special  print 

and  an  instruction  limit  of  100   . 

(2)  '2000;123J4-G'   start  execution  at  2000,  with  no  special  print 

and  an  instruction  limit  of  123^+n* 

(3)  '3000;G0'     start  execution  at  3000  and  print  the  PC  for 

each  instruction  executed. 
(k)      '3000;G1'     start  execution  at  3000  and  print  the  PC,  opcode, 

and  mnemonic  for  each  instruction  executed. 
(5)   'P0'         resume  execution  with  no  change  in  the  instruction 

limit,  and  print  the  PC  for  each  instruction. 
<N0TE:  The  use  of  '/'  to  denote  continuation  allows  the  user, 
when  in  print  mode  0,  to  dump  8  or  9  PC ' s  per  line,  by  typing 
1  /<A.LTM0DE> '  as  a  response. > 

It  is  possible  to  completely  remove  the  limit  on  number  of  instruction 
executed — see  under  '.S/'  in  section  VII. 
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5.6.3  I/O  Conventions,  Dynamic  Core  and  Register  Dumps 

At  present,  DEBETS  supports  only  teletype  I/O  for  the  user's 
program.   This  is  done  as  follows: 

5.6.3.1  Input:   EMT  0,  followed  by  a  buffer  address.   This  causes  DEBETS 

to  read  a  line  from  the  user  and  store  it  in  the 
designated  buffer.   The  terminal  character  (<CK>,  <LE>,  or 
<ALTM0DE>)  is  counted  as  part  of  the  input.   (in 
particular,  if  <CR>  is  the  terminal,  <LF>  is  tacked 
on,  too. ) 

5. 6.3 . 2  Output:  EMT  1,  followed  by  a  buffer  to  be  typed,  which  must  end 

in  a  zero  byte.  No  <.CR>  or  <LF>  is  added  on;  the  user 
must  put  these  in  himself  if  he  wants  them.   The  output 
buffer  may  not  exceed  200   characters. 

(in  point  of  fact,  any  even  EMT  causes  input,  and  any  odd  EMT 

causes  output,  with  the  exceptions  below,  but  since  DEBETS  plans 

using  other  EMT's  for  special  purposes  later,  it's  best  to 

restrict  oneself  to  EMT  0  and  EMT  1.) 

The  user  can  get  core  dumps  under  program  control  by  using  one  of 
the  following  three  special  EMT's.   In  each  case,  the  EMT  must  be  followed 
by  2  words  giving  the  low  and  high  addresses  for  the  dump: 

EMT  375  -  dump  in  word  mode 

EMT  376  -  dump  in  byte  mode 

EMT  377  -  dump  in  ASCII  mode 

The  user  can  selectively  dump  registers  during  program  execution 
by  using  the  TBAP  instruction.   In  this  case,  the  low  byte  of  the  instruction 
(the  trap  number)  is  scanned  right-to-left,  and  registers  corresponding  to 
1-bit s  are  dumped.   For  example, 
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TRAP  1   dumps  RO 

TRAP  200  dumps  RT 

TRAP  2^5  dumps  RO,  R2,  R5,  RT 

TRAP  377  dumps  all  8  registers. 

TRAP  0  is  a  special  exception.  When  the  user  executes  this,  his 
program  is  given  control  of  the  TRAP  instruction,  and  may  use  it  as  described 
in  the  PDP-11  handbook.  Another  TRAP  0  returns  TRAP  to  its  register 
dumping  function.   (Then  another  TRAP  0  gives  the  user  control  of  TRAP, 
and  so  on. . . ) 

5.6.4  Error  Messages 

As  DEBETS  executes  a  user  program,  it  checks  for  a  variety  of 
errors,  such  as  addresses  out  of  range  or  attempts  to  access  words  at  odd 
addresses.  When  DEBETS  finds  an  error,  it  stops  execution  of  the  program, 
prints  out  the  PC,  opcode  and  mnemonic  for  the  instruction  in  error,  plus 
an  explanatory  error  message,  and  returns  to  command  mode.   Following  is 
a  list  of  possible  error  messages.   The  lack  of  continuity  in  the  numbers 
is  the  programmer's  fault,  not  DEBETS' s. 
#1:   JUNK 

The  user  tried  to  execute  a  non-opcode. 
#2:   RESERVED  OP. 

The  user  tried  to  execute  WAIT,  RESET,  or  RALT. 
(Usually  DEBETS  does  not  actually  execute  HALT'S,  since 
they're  used  as  breakpoint  flags.  However,  if  the  user 
does  a  proceed  from  a  HALT,  DEBETS  attempts  to  execute  it 
and  flags  error  #2 . ) 
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#3:    ODD  REG  IN  MODE  3- 

In  address  mode  3,  the  register  is  supposed  to  contain 
the  address  of  a  pointer,  so  this  address  must  be  even. 
jfh.        ODD  PTR  IN  MODE  7. 

In  address  mode  7>  "the  register  contents  are  added  to 
an  index  word  to  get  the  address  of  a  pointer.   This  address 
must  be  even. 
#5:    ODD  ADDR  IN  WORD  OP. 

The  user  tried  to  access  a  word  at  an  odd  address. 
#6:    ODD  REG  IN  MODE  5. 

This  is  similar  to  #3 — the  register,  after  being 
decremented,  must  contain  the  address  of  a  pointer,  so  this 
address  must  be  even. 

#8:   ADDR  TOO  BIG. 

The  user  tried  to  access  out  of  his  area.   Because 
DEBETS  uses  unsigned  comparisons,  an  address  of  -1,  say, 
looks  too  big  to  it. 
#10:   BUFFER  OUT  OF  RANGE. 

On  an  I/O  instruction,  the  buffer  address  following 
the  instruction  was  too  large. 
#11:   1"ST  BYTE  OF  BUFFER=0. 

On  an  output  instruction,  the  trailer  byte  came  a  bit 
too  soon. 
#12:   BUFFER  LENGTH  >200. 

DEBETS  does  not  permit  outputting  more  than  200 
characters  with  one  instruction.   This  is  to  protect  against 
the  user's  forgetting  the  trailer  byte  on  the  buffer  and 
then  outputting  some  large  chunk  of  his  program. 
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#13:      BAD  PC. 

The  user  executed  an  instruction  which  changed  the  PC 
to  something  odd  or  out  of  bounds.   This  can  happen  if  the 
user  is  doing  arithmetic  on  the  PC,  or  if  he  executes 
an  interrupt  and  the  interrupt  vector  contains  a  bad  value 
for  the  PC. 

#1)+:   BAD  STACK  PTR. 

The  user  executed  an  instruction  which  uses  the  stack 
pointer,  and  the  latter  was  found  to  be  odd  or  out  of 
bounds.   For  instance,  JSR  pushes  one  word  onto  the  stack. 
If  the  stack  pointer  is  0  at  the  time,  an  error  will  result, 

#15:   STOP! 

The  user  typed  control-Q  or  control-V  during  the  course 
of  program  execution.   This  is  the  way  to  exit  from 
tediously  long  loops  or  just  a  way  to  get  back  to  command 
mode.   The  user  should  be  careful  using  this,  since,  once 
DEBETS  is  back  in  command  mode,  typing  control-Q  returns 
the  user  to  ETS. 
#16:   LO  DUMP  ADDR  TOO  BIG. 

The  user  has  requested  a  dump  with  EMT  375,  376  or  377, 
and  the  low  address  is  out  of  bounds. 
#17:   HI  DUMP  ADDR  TOO  BIG. 

A  dump  was  requested  and  the  high  limit  was  too  large. 
#18:   LO  DUMP  ADDR  NOT  <  HI  ADDR. 

The  low  address  for  a  dump  should  be  less  than  (or 
equal)  to  the  high  address. 


ETS   Student's  Guide 


-31- 


July  1972 


5.7.1 

1 .<number>/' 

' .<number>\! 

5.7.2 

•.R' 

5.7.3 

'.N' 

5.7  Special  Routines 

There  are  a  number  of  special  little  routines --among  them  the 

routines  for  opening  register—which  are  called  by  typing  '.'  (dot)  plus 

some  letter  or  number.   These  are  described  below  under  the  calling  string. 

open  register  <number>;  <humber>  must  be  between 
0  and  7. 

dumps  all  registers,  four  to  a  line. 

dumps  the  instruction  count.   Recall  that  DEBETS 
counts  the  number  of  instructions  the  user 
program  executes.  When  the  user  returns  to 
command  mode,  this  number  can  be  dumped.  Note, 
however,  that  the  instruction  count  is  set  to  0 
by  each  P-  or  G-  command,  and  that  it  is  reset 
before  each  instruction  executed  in  a  non-'null' 
print  mode  and  after  an  instruction  limit 
interruption. 

dumps  the  "PC  stack'.  As  the  user  program 
executes,  DEBETS  keeps  an  8-word  stack  containing 
the  most  recent  8  values  of  the  user's  PC.   The 
1 .P'  command  dumps  these  8-values,  with  the  most 
recent  one  first. 


5.7.^ 


.P' 


5.7.5  '.C 

5.7.6  '.c/' 

5.7.7  '.S/' 


dumps  the  current  value  of  the  user's  condition 
code  in  the  format  'CVZN=nnnn' — in  which,  for 
instance,  the  value  of  the  C-bit  is  the  first  0 
or  1  to  the  right  of  the  equal  sign. 

dumps  the  user's  condition  code  as  above,  then 
opens  the  user's  program  status  register. 

opens  the  'print  register'.   This  word  is 
normally  non-zero.   If  the  user  alters  it  to 
zero,  he  thereby  disables  the  instruction  limit 
on  executing  his  program.   Then,  when  he  gives 
a  P-  or  G-  command,  and  provided  he  omits  the 
print  mode  (print  mode  is  'null');  DEBETS  types 
the  message  'PRINT  BOMBED.   OKAY?'.   If  the  user 
responds  with  'Y',  DEBETS  begins  execution  with 
no  limit  on  the  number  of  instructions  executed. 
If  DEBETS  encounters  no  breakpoints,  HALT'S,  or 
fatal  errors,  it  will  continue  executing  the  user 
program  until  the  user  types  control-Q  or  control-V. 
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5.7.8  '.B/'  causes  DEBETS  to  type  the  numbers  of  the 

breakpoints  which  are  currently  set. 

5.7.9  '.B<n>,        -where  <n>  is  an  octal  number  from  0  to  27n, 

starts  an  examination  of  the  breakpoint  table, 
with  breakpoint  number  n.   If  n  is  absent  and 
there  is  no  slash  after  '  BT,  the  examination 
begins  with  breakpoint  0.  Whereever  the 
examination  begins,  DEBETS  scans  the  table 
until  it  finds  a  breakpoint  that  is  set.   Then 
it  dumps  the  breakpoint  number  and  the  address 
of  the  breakpoint,  in  the  format  ' Bnnn=mmmmmm' . 
Following  this,  it  dumps  the  repeat  count  for 
that  breakpoint  and  waits  to  allow  the  user  to 
change  it.  Whether  the  user  types  a  number  or  not, 
if  the  user  then  types  line  feed,  DEBETS  continues 
scanning  the  breakpoint  table  until  it  hits  the 
next  breakpoint  that  is  set,  or,  failing  this, 
returns  to  command  mode.   If  the  user  does  not 
type  line  feed,  DEBETS  returns  to  command  mode. 

<N0TE:   The  sequence  ' .  B<n,  ALTM0DE> '  allows 
convenient  changing  of  the  repetition  factor  for 
breakpoint  $n  on  one  line  of  print. > 

5.7*10    ' .HT  causes  DEBETS  to  type  the  highest  address  currently 

available  to  the  user. 


5.8  Dynamic  Symbol  Table 

Ideally,  a  debugging  package  should  allow  its  user  to  reference 
core  locations  using  the  same  symbols  the  user  has  defined  in  his  assembly 
listing.   Unfortunately,  this  is  at  present  not  possible  with  DEBETS;  the 
problems  of  passing  a  symbol  table  from  ASSETS  to  DEBETS,  and  the  high 
overhead  involved  in  doing  multiple  disk  accesses  to  get  at  symbols  make 
it  infeasible  for  the  time  being.  However,  DEBETS  does  keep  a  small 
table  with  space  for  (at  present)  ^01Q  symbols.   There  are  commands  for 
defining  symbols,  re-defining  them,  deleting  them,  and  for  clearing  the 
entire  table.   These  commands  are  described  below.   The  user-defined 
symbols  are  used  in  the  following  ways: 
5.8.1  Commands 

5.8.1.1  If  a  breakpoint  interrupt  occurs  at  location  <addr>,  DEBETS 
searches  the  symbol  table  for  a  symbol  with  value  <addr>.   If  it  finds 
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such  a  symbol  it  types  the  symbol  as  part  of  the  breakpoint  message.   If, 
for  example,  a  breakpoint  interrupt  occurs  at  location  123^4-  and  symbol 
XYZ  has  value  123^-,  the  message  will  look  like 

'BnrXYZ  =  1231*-'. 

If  DEBETS  finds  no  symbol  with  the  required  value,  it  merely  dumps  the 

address,  as  already  described.   This  feature  makes  identification  of 

breakpoints  much  easier. 

5.8.1.2  When  DEBETS  dumps  the  'PC  stack'  (see  section  5-7,  under  '.P') 

it  dumps  a  symbol  for  each  value  of  the  PC  if  it  finds  a  symbol  with  that 

value. 

5.8.1-3  When  DEBETS  dumps  the  address  of  an  instruction  in  disassemblies, 

it  dumps  a  symbol  if  there  is  one  whose  value  is  the  address. 

5.8.1.U  The  mini -assembler  (see  section  5*10)  allows  symbolic  referencing 

in  an  instruction  patch. . 

Commands  to  the  symbol  table  handler  consist  of  the  letter  'S' 
followed  by  a  series  of  'fields'  specifying  operations  to  be  performed. 
These  fields  may  be  optionally  separated  by  slashes  ('/').   The  slashes 
are  used  for  error  recovery:  if  a  field  looks  bad  or  unintelligible  to 
DEBETS,  it  scans  the  input  until  it  finds  a  slash,  then  resumes  processing 
of  fields.  The  following  are  the  formats  of  valid  fields: 
5.8.2  Field  Formats 

5.8.2.1    Symbol  definition: 

<symbol>=<value>       defines  a  symbol  with  a  given 

value,  e.g.,  ABC  =  12^56. 

<symbol>=!<value>       defines  a  symbol  with  a  given 

value;  if  the  symbol  has  already 
been  defined,  it  is  to  be  re-defined. 
E.g«,  if  A  has  already  been  defined 
to  have  value  111,  then  A  =  !222 
redefines  it  to  have  value  222. 
Just  A  =  222  results  in  an  error 
message  telling  that  A  is  already 
defined. 
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<symbol>=<value>;nB 
or  <symbol>=!<value>;hB 


defines  a  symbol  with  a  given  value, 
then  sets  a  breakpoint  at  address 
<value>.   E.g.,  A  =  1000 ;B  defines 
A  to  have  value  1000,  then  sets  the 
location  1000.   Similarly,  A  =  1000; 2B 
defines  A  to  have  value  1000,  then 
sets  breakpoint  2  at  1000. 


<Note:   Symbols  must  obey  standard  PAL  convention, 


i.e. 


must 


consist  of  characters  A-Z,  0-9,  '$',  and 


and  must  begin 


with  A-Z,  '$',  or 
are  truncated. > 

5.8.2.2     Symbol  deletion: 

-<symbol> 


Symbols  longer  than  6  characters 


deletes  <symbol>  from  the  table. 
E.g.,  -XYZ  deletes  XYZ.   These  may 
be  strung  together,  e.g.,  -A-B-FGH-J 
to  delete  A,B,FGH,  and  J. 


-<symbol>;B 


5.8.2.3 

5.8.2A 
5.8.2.5 


?<value> 


< 


deltes  <symbol>  from  the  symbol 
table.   If  a  breakpoint  is  set  at 
location  <value  of  symbol>,  it  is 
deleted.  E.g.,  if  A  =  1000  and 
a  breakpoint  is  set  at  1000,  then 
' S-A;B'  deletes  the  symbol  A  and 
the  breakpoint  at  1000. 

deletes  all  symbols  from  the  table. 

types  out  all  symbols  with  a  given 
value . 

dumps  all  the  symbols  presently  defined. 

returns  DEBETS  to  normal  scanning 
immediately  following  '<' .   For 
instance,  suppose  in  one  command 
a  symbol  and  breakpoint  are  defined: 
A  =  1000 ;2B.   Later,  the  user  decides 
to  get  rid  of  A  and  the  breakpoint. 
He  can  do  so  with  'S-A<;2B' .   This 
deletes  A,  returns  to  normal 
scanning,  then  deletes  breakpoint 
2.   This  may  of  course  also  be  done 
with  'S-A;B'. 
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5.9  Storing  and  Later  Retrieval  of  DEBETS  Command  Strings 

The  commands  typed  to  DEBETS  are  received  as  strings  of  ASCII 
characters  which  DEBETS  scans  for  certain  characters  which  represent 
operations  to  be  performed.   It  is  possible  for  DEBETS  to  get  such  a 
string  from  anywhere  in  core.   In  particular,  the  user  can  place  an 
ASCII  string  somewhere  in  his  area,  then  tell  DEBETS  to  use  it  as  the 
next  command  string.   There  are  three  ways  to  do  this: 

5.9.1  In  tells  DEBETS  to  find  its  next 

command  string  at  breakpoint  n. 
E.g.,  if  breakpoint  20  is  set  at 
123k,    120  causes  DEBETS  to  process 
the  string  at  123^  • 

5.9.2  F<symbol>  causes  DEBETS  to  process  the  string 

at  address  <value  of  symbol>. 
E.g.,  'FLOP'  causes  DEBETS  to  look 
up  'LOP'  in  the  symbol  table.   If 
it  doesn't  find  'LOP',  it  flags  an 
error.   Otherwise,  if,  say,  'LOP'  = 
123^,  DEBETS  processes  the  command 
string  at  user  location  123^  • 

5«9«3         F<address>  causes  DEBETS  to  process  the  string 

at  <address^,  e.g.,  F123^  causes  it 
to  process  the  string  at  user  location 

<Note:   If  DEBETS  is  processing  a  command  string  from  user 
area  and  encounters  an  'I1  or  'F'  command,  it  flags  an 
error  and  returns  to  normal  command  mode.> 

5.10  Symbolic  Program  Patching — the  Mini -Assembler 

If  the  user  wishes  to  insert  an  instruction  in  a  certain 
location,  he  can  do  so  by  typing  l<address>:<instr>* .   DEBETS  then 
assembles  the  instruction,  inserts  it  at  <address>  (provided  <address> 
is  even),  and  prints  out  the  location  following  the  last  word  inserted 
followed  by  a  colon. 

The  instruction  to  be  assembled  may  be  virtually  any  valid 
instruction  or  a  single  symbol.   The  user  should  use  registers  R6  and 
R7,  not  the  symbols  SP  and  PC.   DEBETS  will  consider  SP  and  PC  as  user 
defined  symbols.   If  the  instruction  contains  a  symbol  that  is  not  in 
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the  dynamic  symbol  table,  it  will  print  out  the  undefined  symbol, 
followed  by  a  question  mark.   The  user  may  then  define  the  symbol  by 
typing  its  value,  followed  by  a  <CE>.   The  user  may  return  to  command 
mode  by  typing  a  <CR>  without  giving  any  value. 

DEBETS  checks  for  a  variety  of  errors,  such  as  addresses  out 
of  range  or  attempts  to  assemble  instructions  at  odd  locations.  Usually 
when  an  error  is  detected,  an  error  message  is  printed,  and  DEBETS  prints 
out  the  original  location  number  (if  valid),  followed  by  a  colon,  so 
the  user  may  enter  the  corrected  instruction.  Following  is  a  list  of 
possible  error  messages. 

#1:  ATTEMPT  TO  ASSEMBLE  AT  ODD  LOCATION 

The  location  given  was  odd.   DEBETS  increments  it 
and  prints  it  followed  by  a  colon,  so  the  instruction 
may  be  reinserted. 
fd:     ADDR  TOO  BIG 

The  location  given  was  outside  the  user's  area. 
DEBETS  returns  to  command  mode. 

For  the  following  errors,  DEBETS  prints  the  error  message  and 
allows  the  user  to  insert  a  corrected  instruction  in  the  original  location. 
#3:   BRANCH  OFFSET  SIZE  ERROR 

The  location  to  be  branched  to  is  out  of  range  of 
the  branch  instruction. 
#<■:   TOO  MANY  OPERANDS 

The  user  has  typed  an  instruction  with  more  than 
two  operands. 
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#5:   INVALID  OPERAND 

This  includes  errors  in  usage  such  as  RTS  @7fLABEL 
as  well  as  syntactical  errors  like  TST  -(R^)+. 
#6:   INVALID  MNEMONIC 

The  mnemonic  given  was  invalid.   Symbols  to  be 
inserted  have  no  operands,  e.g.,  1020:   SYMBOL  is  a 
valid  insertion,  whereas  1020:   SYMBOL  <operand>  will 
flag  error  #6. 
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6 .      GIZMO 

GIZMO  was  designed  to  aid  CS  201  students  in  learning  basic  assembly 
language  concepts.   It  is  very  easy  to  use. 

6.1  GIZMO  is  invoked  by  typing 

RIM  STUD 
"when  in  monitor  command  mode.  GIZMO  will  then  ask  you  to  identify  yourself. 
Please  type  your  name  followed  by  a  return.  GIZMO  will  then  ask  for  a 
lesson  name.   Please  type  the  name  of  the  lesson  that  your  T.A.  has  indicated. 

6.2  GIZMO  will  ask  you  a  series  of  questions.  Answer  each  one  and  terminate 
each  response  with  a  carriage  return.   If  you're  correct,  GIZMO  will 
usually  say  "very  good."  Otherwise,  it  will  attempt  to  give  you  some  helpful 
hints.   If  you  are  sure  your  answer  is  correct,  and  GIZMO  says  you're  not, 
please  call  your  T.A.  for  assistance. 

6.3  If  you  have  no  idea  what  the  correct  answer  is,  you  may  ask  for  help 
hy  typing  HELP.   If  you  want  to  give  up,  type  GIVE-UP. 

6.1+  The  lesson  has  been  completed  when  GIZMO  asks  you  to  identify  yourself 
again . 
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